home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / scan.n < prev    next >
Encoding:
Text File  |  1994-09-20  |  6.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. scan(n)               Tcl Built-In Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      scan - Parse string using conversion specifiers in the style
  12.      of sscanf
  13.  
  14. SYNOPSIS
  15.      scan _s_t_r_i_n_g _f_o_r_m_a_t _v_a_r_N_a_m_e ?_v_a_r_N_a_m_e ...?
  16. _________________________________________________________________
  17.  
  18.  
  19. INTRODUCTION
  20.      This command parses fields from an input string in the  same
  21.      fashion  as  the ANSI C sscanf procedure and returns a count
  22.      of the number of fields sucessfully  parsed.   _S_t_r_i_n_g  gives
  23.      the input to be parsed and _f_o_r_m_a_t indicates how to parse it,
  24.      using % conversion specifiers as in  sscanf.   Each  _v_a_r_N_a_m_e
  25.      gives  the  name of a variable; when a field is scanned from
  26.      _s_t_r_i_n_g the result  is  converted  back  into  a  string  and
  27.      assigned to the corresponding variable.
  28.  
  29.  
  30. DETAILS ON SCANNING
  31.      Scan operates by scanning _s_t_r_i_n_g and _f_o_r_m_a_t_S_t_r_i_n_g  together.
  32.      If the next character in _f_o_r_m_a_t_S_t_r_i_n_g is a blank or tab then
  33.      it is ignored.  Otherwise, if it isn't a % character then it
  34.      must  match  the  next  non-white-space character of _s_t_r_i_n_g.
  35.      When a % is encountered in _f_o_r_m_a_t_S_t_r_i_n_g,  it  indicates  the
  36.      start  of  a  conversion  specifier.  A conversion specifier
  37.      contains three fields after the %: a *, which indicates that
  38.      the  converted  value is to be discarded instead of assigned
  39.      to a variable; a number indicating a  maximum  field  width;
  40.      and  a  conversion  character.   All  of  these  fields  are
  41.      optional except for the conversion character.
  42.  
  43.      When scan finds a conversion specifier in  _f_o_r_m_a_t_S_t_r_i_n_g,  it
  44.      first  skips  any white-space characters in _s_t_r_i_n_g.  Then it
  45.      converts the next input characters according to the  conver-
  46.      sion  specifier  and stores the result in the variable given
  47.      by the next argument  to  scan.   The  following  conversion
  48.      characters are supported:
  49.  
  50.      d         The input field must be a decimal integer.  It  is
  51.                read in and the value is stored in the variable as
  52.                a decimal string.
  53.  
  54.      o         The input field must be an octal  integer.  It  is
  55.                read in and the value is stored in the variable as
  56.                a decimal string.
  57.  
  58.      x         The input field must be a hexadecimal integer.  It
  59.                is read in and the value is stored in the variable
  60.  
  61.  
  62.  
  63. Tcl                                                             1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. scan(n)               Tcl Built-In Commands
  71.  
  72.  
  73.  
  74.                as a decimal string.
  75.  
  76.      c         A single character is read in and its binary value
  77.                is  stored  in  the  variable as a decimal string.
  78.                Initial white space is not skipped in  this  case,
  79.                so the input field may be a white-space character.
  80.                This conversion is different from the  ANSI  stan-
  81.                dard  in that the input field always consists of a
  82.                single character and no field width may be  speci-
  83.                fied.
  84.  
  85.      s         The input field consists of all the characters  up
  86.                to  the next white-space character; the characters
  87.                are copied to the variable.
  88.  
  89.      e or f or g
  90.                The input field must be  a  floating-point  number
  91.                consisting  of  an  optional  sign,  a  string  of
  92.                decimal digits  possibly  con  taining  a  decimal
  93.                point, and an optional exponent consisting of an e
  94.                or E followed by an optional sign and a string  of
  95.                decimal  digits.   It is read in and stored in the
  96.                variable as a floating-point string.
  97.  
  98.      [_c_h_a_r_s]   The input field consists of any number of  charac-
  99.                ters  in  _c_h_a_r_s.  The matching string is stored in
  100.                the variable.  If the first character between  the
  101.                brackets  is  a  ]  then  it is treated as part of
  102.                _c_h_a_r_s rather than the closing bracket for the set.
  103.  
  104.      [^_c_h_a_r_s]  The input field consists of any number of  charac-
  105.                ters  not in _c_h_a_r_s.  The matching string is stored
  106.                in the variable.   If  the  character  immediately
  107.                following  the ^ is a ] then it is treated as part
  108.                of the set rather than the closing bracket for the
  109.                set.
  110.  
  111.      The number of characters read from the input for  a  conver-
  112.      sion is the largest number that makes sense for that partic-
  113.      ular conversion (e.g.  as many decimal  digits  as  possible
  114.      for %d, as many octal digits as possible for %o, and so on).
  115.      The input field for a  given  conversion  terminates  either
  116.      when a white-space character is encountered or when the max-
  117.      imum field width has been reached,  whichever  comes  first.
  118.      If  a * is present in the conversion specifier then no vari-
  119.      able is assigned and the next scan argument is not consumed.
  120.  
  121.  
  122. DIFFERENCES FROM ANSI SSCANF
  123.      The behavior of the scan command is the same as the behavior
  124.      of  the  ANSI  C  sscanf  procedure except for the following
  125.      differences:
  126.  
  127.  
  128.  
  129. Tcl                                                             2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. scan(n)               Tcl Built-In Commands
  137.  
  138.  
  139.  
  140.      [1]  %p and %n conversion specifiers are not currently  sup-  |
  141.           ported.
  142.  
  143.      [2]  For %c conversions a single  character  value  is  con-
  144.           verted  to  a decimal string, which is then assigned to
  145.           the corresponding _v_a_r_N_a_m_e; no field width may be speci-
  146.           fied for this conversion.
  147.  
  148.      [3]  The l, h, and L modifiers are ignored;  integer  values  |
  149.           are  always  converted  as  if  there  were no modifier  |
  150.           present and real values are always converted as if  the  |
  151.           l  modifier  were present (i.e. type double is used for  |
  152.           the internal representation).
  153.  
  154.  
  155. KEYWORDS
  156.      conversion specifier, parse, scan
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tcl                                                             3
  196.  
  197.  
  198.  
  199.